
TO WORD WRAP THIS TEXT:

Click Edit on this screen's above toolbar and then click on Word Wrap.

TK3 GENERAL NOTES - 08AUG04

Some of this information may update that given in the published EPE TK3 text.

Always check the Updates file for any information that affects these notes. It is normally issued whenever an update to TK3 is released and is accessible via the "Latest Updates" button at the bottom of the main TK3 screen.


These notes generally refer to the option buttons in the main screen area captioned GENERAL, although some other information is also given. Other matters are discussed through the various NOTES buttons variously used on the main screen and elsewhere.

ABOUT TOOLKIT

If you have not already read the notes displayed via the About Toolkit button on the main screen, please do so now. That screen also allows you to select the Check PCB option (which has further notes as well), although this option is also available by the same-named main screen button.

SELECT TEXT EDITOR

The default text editor used by TK3 is Windows Notepad. However, for viewing all user-created files (except the NOTES files), you may choose any other text editor you prefer. Details of selection are given when you click the Select Text Editor on the main screen.

There are more notes on that screen but it is worth noting that the NOTETAB LIGHT text editor listed is one that was recommended to the author by EPE reader Richard Neill. It is available for free download from web site WWW.NOTETAB.COM (address is included in TK3's Internet access library). NOTETAB has not been thoroughly tested by the author but it appears to offer a wealth of facilities that seem to make it a worthwhile editor to consider using in place of Notepad. For copyright reasons we cannot include it with TK3's suite of files. The zipped download file length is about 1.5Mb. Thank you Richard!

The facility to swap between two editors without going through the main selection process each time is included - see notes on Set Text Editor screen.

DIRECTORY ACCESS

The directory (folder contents) screen, which is accessible via the DIR buttons, has its own NOTES button giving details. You may also search for files (but not select for use by TK3) using Windows' own Find facility, accessible in the usual way via the Windows Start button at the bottom left of the screen.

TAB BUTTON

This option allows the tab lengths used in the TASM to MPASM ASM conversion routine to be changed if preferred. Click it to set spacing in steps of 8, from 8 to 32, then rollover to 8 again.

Since TK3 V2 the program no longer aborts if an inadequate Tab length is selected and in most cases you can probably leave it set at 16.

POWER AND CABLE CHECK

Before any attempt at communication with the PIC is made from any function button, and if the Verifying option is in use (see Verifying notes viewable via the Check PCB button on the main screen), a check is made to determine if the printer port cable is connected and the PCB power is on. A message box appears if either of these conditions is false.

ERASE PIC

Sending configuration data to a PIC (via the PIC Configuration option on the main screen) does not erase program codes held within it (unlike earlier Toolkit versions). Nor does Configuring a PIC erase its Eeprom data memory.

Clearing of program and Eeprom data memory codes can be done using the Erase PIC button on the main screen, which takes you to a sub-window allowing choice of whether program or Eeprom memory is cleared. The Erase Program function uses an erasure code that reads back as a value of 63 when the PIC is disassembled to an ASM file. The Erase Eeprom function uses an erasure code that reads back as a value of 0 when the PIC is read back to an MSG file. Erasing the memory does not affect the PIC's Config settings.

BIN-HEX-DEC

Although TK3's various ASM handling routines all recognise and translate binary and hexadecimal to decimal, it is often useful to program designers to know the information directly. A tri-directional binary-hex-decimal facility is included with TK3 via the button labelled BIN-HEX-DEC on the main screen.

A similar facility was originally included with EPE Teach-IN 2000 and proved so useful that it has been modified to suit TK3. It handles binary values up to eight bytes (64 bits) long, hex up to FFFFFFFF FFFFFFFF, and decimal to 1.84467440737096E+19 (a mighty large number that the author's computers refuse to expand further!).

You may choose to set the conversion for entry in binary, hex or decimal using the option click boxes provide. All entries are then regarded by the program as being in that form. That is, with binary as the option, an entered value of 1111 would be treated as though it is the binary byte value 00001111 (decimal 15). With hex as the selection the same value would be treated as 1111h (decimal 4369). In the decimal option it would be treated as you might expect.

You may also select Mixed Entry in which any binary, hex or decimal entry can be made as required, the type of conversion to be performed being specified by the prefix given to the value. Binary values should be prefixed by the percent symbol (%). Values which are prefixed by
the dollar symbol ($) or commence with letters A to F or H are treated as hexadecimal. Other values above zero are treated as decimal. This information is also shown on screen when the Mixed Entry option is selected (this is the default option each time TK3 is loaded).

The data entry box is automatically cleared when the conversion is performed (press Enter or click on the Convert button), ready for the next value to be entered. However, you may also click the Show Last Entry Again button for the same value to be displayed again. This allows closely similar values to be readily entered just by changing part of the value, which saves the tedious task of typing it all in again! (The author thinks you are likely to be just as impatient on
such matters as he is!)

Another facility has also been included, that of having the powers of two calculated and displayed, up to the value of 2^63 (two to the power of 63). Clicking on the Powers of 2 button reveals a drop-down list with the powers of 2 listed in numerical sequence. Simply click on the
value required and its binary, hex and decimal equivalents are then displayed. Note that powers of 50 and above are displayed in the standard mathematical decimal notation in which the value has a decimal point inserted and a suffix added, such as E+19 for example (as given above). This is a limitation imposed by Visual Basic 6 (in which the program has been written), not by the author.

COMMANDS

The full set of PIC commands that TK3 recognises is viewable via the main screen Commands button. They are principally those specified in Microchip's PIC data sheets (all the "conventional" commands, plus a few "shorthand" commands with which some MPASM users may be already be familiar). When writing PIC source code, you can only include PIC commands that are listed (but also see the Assembly Notes, which cover the use of Include files and Data statements).

Note that TK3 does not not claim to offer full compatibility with all files created using MPASM grammar. If statements which TK3 does not recognise occur in files, it is up to the user to translate the commands to a more simple form. However, we will be pleased to learn of any which are found and which you think should be included.

INTERNET

Because Visual Basic 6 allows easily programmable Internet access, this highly beneficial facility has been included with TK3. It does require, though, that your computer has Microsoft Internet Explorer already installed, and that you have a valid account with any Internet server (e.g. Compuserve, AOL, Demon, Freeserve, etc), plus a modem.

Clicking the Internet button if your PC does not have Internet access may result in unpredictable errors but should not "crash" the program. 

The access commands used in the program are those given in the Microsoft book Learn Visual Basic 6.0 Now (the TK3 program is written in VB6). They worked as expected on Windows 95 and 98 machines that had access to the Internet via Microsoft Internet Explorer 5 (IE5).

Three situations arose on other machines. On a Win 95 machine with Internet Explorer 4 installed, access to the Web was denied. On another Win 95 PC that had IE5 but was without a modem, the PC simply asked if it should locate a modem. A third machine having Win 98 and IE5 but had never been used for Web access tried to "sign-up" the author to IE5, even though the PC did not have a modem.

Whilst the book stated that IE4, IE5 (or later) could be used, it is only IE5 that has allowed the author to access the Internet access via the book's code lines. Reader feedback on this will be welcomed.

Clicking the main screen Internet button reveals a window displaying a selection of Internet addresses, those which the author finds the most useful in the context of PIC and Visual Basic programming, and EPE of course! The following is the list:

http://www.epemag.wimborne.co.uk (EPE home site)
http://www.epemag.com (EPE Online site)
ftp://ftp.epemag.wimborne.co.uk/pub/PICS (EPE PIC source code download)
http://www.microchip.com (Microchip for PIC data etc)
http://www.microsoft.com (Microsoft Corp. home page)
http://mspress.microsoft.com (Microsoft Press home page)
http://msdn.microsoft.com/vbasic (Microsoft Visual Basic home page)
http://www.windx.com (Fawcette Publications VB resources)
http://www.cgvb.com (Carl and Gary's VB home page, non-Microsoft)
http://www.google.com (Excellent search engine)
http://www.lvr.com (Software site recommended by Robert Penfold)
http://www.pdsl.com (Public Domain Shareware Library, UK)
http://www.kellysearch.com (In-depth manufacturer search site)
http://www.notetab.com (Freeware text editor download site)

Clicking on a web address selects it and also displays similar descriptions to those in brackets above. Having selected the site, click Go On-Line (or double-click the address). This transfers control to Internet Explorer, which accesses the web site via your normal server. Exiting from Internet Explorer returns you to the same TK3 screen after having asked you to confirm that the web link should be terminated. However, if you choose, you can remain on-line and select another of TK3's listed sites in order to enter it.

You may also add your own favourite sites which you think might be useful to access via TK3, and also to remove those you no longer want. There is a button for each facility.

When adding addresses, you are offered two text boxes, one for the web address and the other for its brief description. Click on them in order to select them. The text can be longer than the boxes and you can pan along them using the cursor keys.

In this mode, a Store New Web Address button is shown, simply click on it to add your text box details to the list. This is automatically saved to your hard disk ready for future recall.

Existing web addresses may be edited via the Edit Web Address File button. Clicking the button loads the data into a Windows Notebook screen (such as you are viewing now) from where any of the text can be edited in the usual way, and resaved under the same file name.

Note, though, that the hash symbol (#) must be retained (with a space to each side) to allow TK3 to differentiate between web addresses and their descriptions (you are reminded of this from the web access screen). The following is an example:

http://www.epemag.wimborne.co.uk/ # EPE home site

Having saved an edited file, the revised file data can be reloaded to the screen by clicking on the now-revealed Reload Edited Web File button. (The file is automatically reloaded when adding an address via the Add option.)

To exit the web access screen, click on Cancel.

COMPARE FILES

The Compare Files facility is one used by the author when writing and testing TK3. It allows two binary (OBJ) or HEX file codes to be compared byte for byte as ASCII values, advising of any differences found. Values are shown in hex.

It includes its own access to the directory facility allowing paths and file names to be selected. An option button selects whether the directory shows files ending in OBJ or HEX. Double-clicking on the selected file name selects it for the comparison routine. The directory
normally has to be accessed twice, clicking on the DIR1 or DIR2 button as appropriate to select the two files needed. The file names are stored when the Compare window is closed via the Quit button, and recalled the next time the window is opened. The stored names are retained when TK3 is closed.

If files of differing lengths are compared, their lengths are reported as different and the comparison takes place just for the length of the shorter file, the comparison being terminated at that point. The number of comparison differences are shown at the top right of the screen.

Whilst the Compare facility is not one normally required for PIC programming, it is an option that has been retained beyond the author's development of TK3 in case some of you may find a use for it. If you want to just try and see how it works, select the same file name twice for one test, and then select two very different files and observe how comparison errors are reported.

With TK3 V2 the option to show any hex line as decoded text has been provided. Double-click on any hex line for the line interpretations to be shown in the two list boxes at the bottom of the screen. Any differences between the two boxes are highlighted. If the word UNFOUND shows for some commands this is likely to be because the PIC type for which the hex file has been assembled has not been selected correctly via the Select PIC Type facility on the main screen. If you do not already know the correct PIC type, there is no way to determine it from a hex file and you must use trial and error in this instance. There is, of course, the possibility that the unfound command may be due to corruption of the hex data file at that point.

CREATING NEW FILES

New files may be created from within TK3's Directory (DIR) screen. The files are automatically assigned the same directory (folder) path and extension that is current for the route from which DIR has been called. DO NOT attempt to change these parameters from within the Directory option, since unpredictable errors could occur. If you need to change a file's path and extension, this should only be done outside TK3's environment (i.e. through Windows own facilities). 

File creation is limited to extensions ASM, INC (from the Assembly DIR buttons) and MSG (via the Message DIR button). The Directory's file creation options are hidden when entering from other DIR buttons. If you think this limitation is unreasonable, tell us, but it seems improbable that creation of OBJ and HEX files could ever be needed through manual data entry, or the creation of files that then need conversion from one dialect to another. Text files may be created via the EDIT TXT button.

In the Programming area on the main screen a Create New File button is also included. This has been added so that readers initially unfamiliar with TK3 know where to create new source code files. It provides an identical access to the Directory as does the DIR button next to it, and either button may be used.

EDIT TXT AND EDIT ANY BUTTONS
 
These two buttons allow you to search for files having extension TXT via the EDIT TXT button, and through all files having any extension. Double-clicking on a selected file name loads that file into Windows Notepad, irrespective the file's type. DO NOT make changes to any file called in unless you know what you are doing - even System files can be examined via the EDIT ANY button and you could seriously upset the computer by making changes to them.

CALC BAUD

When writing code for a PIC which uses RS232 interfacing, a configuration value has to to included to set the Baud Rate in respect of the PIC's oscillator rate. This option provides an easy way of establishing the required value.

CONVERTING HEX TO DECIMAL

This option is for information only and has no other practical purpose. It simply converts MPASM HEX file data to decimal for viewing. This decimalised data is not intended for editing or PIC programming use.

PIC ID and Config data lies between hex addresses H'4000' and H'4008' (decimal 16384 to 16392) (PIC addresses H'2000' to H'2008'). Message data lies between hex addresses H'4200' (decimal 16896) (PIC H'2100') upwards, depending on PIC type.

SHOW PIC CODES

This file shows the PIC commands, the subroutine number to which the software jumps during Assembly, their binary codes as used during Assembly, the file and data required (e.g. f,d), the flags affected by each command, and the function of the command. DO NOT CHANGE THIS FILE!

PIC TUTORIAL

THe PIC Tutorial button allows you to read a slightly edited version of the original EPE PIC Tutorial (Mar-May 98) and to access the CD-ROM based PICtutor MK1 program (if installed on your PC). The EPE PIC Tutorial V2 (Apr-Jun 03) cannot be included for copyright reasons. More information can be read via the Notes button once you enter the sub-screen.

MPASM LINK

The MPASM button allows you to enter a sub-window thorugh which you can directly access Microchip's MPASM assembler and its User Guide (if installed on your PC). More information can be read via the Notes button once you enter the screen.

QUIT TOOLKIT TK3

The Quit Toolkit button on the main screen allows you to close and exit from TK3. However, there is an intercept window that appears when the button is clicked. This asks if you really want to exit from TK3, or to return to its main screen if you don't, by means of the Yes and No buttons.

You can also exit from TK3 in the normal Windows fashion of clicking on the X button (Exit) at the top right of TK3's main screen. This screen also includes the usual Minimize, Normal and Maximize buttons next to the X button, allowing you to temporarily hide all or part of TK3's screen in order to access other programs from within the Windows Desk Top or other screen, as you can with most Windows-based programs.

Additionally, you can also finally exit TK3 by double-clicking on the Toolkit Tk3 caption at the bottom of the main screen.

All TK3's sub-windows that appear from time-to-time have a button which allows you to close that window, variously named Exit, Cancel, OK, Quit. Whilst you can close these windows by using the X button at their top right, it is preferable that you use the named button since clicking on it frequently activates a series of commands that help to keep TK3 running smoothly, things like clearing label captions, updating file name storage, for example. Whilst TK3 should not "crash" if these matters are not updated, some subsequent results may be unpredictable in terms of what is shown on screen.

Using the X and the allocated buttons "unloads" that window's code to minimise the amount of memory in use.

Nearly all TK3's sub-windows have their Minimize/Normal/Maximize buttons deliberately disabled (not shown) to also keep matters "clean".

ERROR INTERCEPTION

Numerous error-trapping routines are scattered throughout TK3 in the hope that the program can never "crash". When predictable errors are intercepted (disk not in drive, file not found, etc) an Errors Message box is displayed stating both the error as detected by the computer system, and a clarifying message relating to the routine at which the error is found. Thus if you are trying to access a file from Drive A, the system error might be shown simply as File Not Found Error 53, the TK3 message will tell you the name of the file that cannot be found, along with the file path under which it is being sought.

If a system error occurs for which TK3 does not have a specific message allocated, but an error trapping routine is still included in that sub-program, a general TK3 message will be displayed:

"This error has been intercepted by the PC System, not by Toolkit. If the problem persists please report its details and circumstances of it occurring to John Becker at EPE"

It is just possible, but unlikely, that a system error might occur in a sub-routine that does not have an error trap allocated. In this case the error message would come directly from the computer and not via TK3's Error Message screen.

Whilst I have tried to anticipate everything that could possibly go wrong, it is possible that I may have overlooked something that you might discover. If so, as the message says, please tell me
via the EPE Editorial office. It is imperative that you do contact me there as I shall then be able to deal with the problem. DO NOT try to advise me via the EPE Chat Zone as I do not necessarily look in on it frequently and your message might be missed.

If you are reporting a problem, then I must be told the circumstances involved. It's no good just saying that "It don't work"! I need to know what won't work. In some circumstances I might ask you to send your file that that is causing a problem, for me to examine on my own system. But please DO NOT send me files unless I specifically ask for them.

I naturally expect, of course, that you make sure you are not the cause of the error and have thoroughly read the original EPE text and the Notes that are included with TK3, and know what you can and cannot expect from it.

SEVERAL POSSIBLE REASONS FOR PROGRAMMING PROBLEMS

1.  PIC omitted/incorrectly inserted/wrong type
2.  Power to the PCB is not present or is incorrect
3.  Printer cable not plugged in
4.  Home-made printer cable wrongly connected
5.  Incorrect port address selected on computer
6.  Computer cannot read printer port as input
7.  Verify unavailable with solo PIC Tutorial PCB
8.  PCB and or components faulty

9.  PIC is "Code Protected" (read back data = 0, or all 1s). NB PIC16C84 Config sent with Code Protection on (CP0 = 0) will result in Config Error and not allow it to be programmed.

10. PIC programming pins (RB6 & RB7) are connected to another circuit which is "pulling" them high or low.

11. You are trying to program a non-Eeprom based PIC that has not been erased.

12. A few genuine errors exist - try again.

13. You are not using Toolkit Mk2 or Mk3 hardware!

14. You are using the Toolkit Mk2 (yes, Mk2) PCB but have not made the following additional connection (the TK3 PCB has this connection included). The correction required is that IC5 pin 2 should be linked to the printer cable socket pin 11, the Busy line (DA0 is pin 2, DA1 is pin 3). This allows TK3 software to check if the printer cable is connected and the PCB power switched on.

In Programming mode, an initial check of the PIC's Config status is made before Verifying commences, if the response value is 16383, or zero, the Verification process terminates with the statement "No Response From PIC!" and an errors value of 16383 or zero shown when the Show Errors" button is clicked. These values are typical results for Items 1 to 9.

For Program errors a comparison between the sent and readback codes can be viewed by clicking the "Show Errors" button.

If errors occur in Config mode, examine the Config Status line. Items 1 to 9 are likely to result in a value of binary 11111111111111 or 000000000000.

The Port and PCB can be checked via the "Check PCB" button on the main screen.

Items 2 and 3 are the most likely cause! (Although these matters should be intercepted as stated in the POWER AND CABLE CHECK paragraph above.)

For 4 - 7 refer to the EPE published text.

Note that not all computers can read from the printer port. Reading back is an essential need for verifying, disassembly and Config checking etc.

If 6 or 7 apply it is likely that even though errors are reported the PIC will still have accepted the program or config settings.

VISUAL BASIC

Toolkit TK3 for Windows was developed by the author as a method through which to learn about using Visual Basic 6 (VB6). He had simply intended to upgrade the EPE PIC Toolkit Mk2 to run under Windows.

However, it soon became apparent that VB6's facilities allowed TK3 to be developed as a tremendously enhanced PIC assembly and programming aid. The more the author's VB6 knowledge increased, so additional improvements became obvious and possible.

In effect, TK3 and VB6 became the author's spare-time "obsession" over around eight months (and continues to be so from time to time!).

Originally starting off with VB6 through Michael Halvorson's excellent book Learn Microsoft Visual Basic 6.0 Now (Microsoft Press, ISBN 0-7356-0729-X), plus not only that book's accompanying CD-ROM, but also the full commercial version of Microsoft Visual Basic 6.0 Learning Edition CD-ROM, a grasp of what makes VB6 "tick" soon developed.

There were, though, many areas of grief and midnight oil over some aspects of VB6. Those of you who are in a similar position to the author's original ignorance of VB may find that his researches and implementations through TK3 could be of interest. It is not claimed that his solutions are always "the ideal", but they could well help you with getting to grips vith VB6 for your own applications.

One point of interest, for example, is that having created a VB6 "window" (Form), code previously written under QuickBASIC could be pasted in. Whilst corrections to suit the code to VB6 were required, they were not found to be significantly difficult. The author had feared that code would need to be written from scratch.

So, if you are trying to find out how VB6 can be told to do something, such as access sub-windows or activate message boxes, for instance, have a browse through TK3's VB6 source code.

But PLEASE DON'T ask the author to explain about the way he's written TK3's program! You're on your own with VB6 learning, as he was too. As TK3 proves, he achieved a fair bit for himself and thoroughly recommends that you persevere with VB6 as well - it's worth it!

ADDING YOUR OWN NOTES

These notes are displayed via an "Active" text editor and you may add your own notes to them, saving them to disk in the usual way.


